All DatabasesInside Mac - Basic Toolbox
LNew
LNew Create an empty list
#include <Lists.h> List Manager Package
ListHandle LNew(rView, rDataBnds, cellSize, procID, theWindow, drawIt,
hasGrow, scrollHoriz, scrollVert );
Rect *rView ; list display area, in coordinates local to theWindow
Rect *rDataBnds; list size; e.g., (0,0)(2,7) is 2 wide by 7 high.
Point cellSize ; size of each cell, in pixels; (0,0)=auto calc
short procID ; resource ID of 'LDEF' proc (0=use standard)
WindowPtr theWindow ; window in which to display the list
Boolean drawIt ; 1=display immediately, 0=delay
Boolean hasGrow ; 1=leave room for an "grow box", 0= won't grow
Boolean scrollHoriz ; 1=draw horizontal scroll bar
Boolean scrollVert ; 1=draw vertical scroll bar
returns handle to variable-length ListRec structure
LNew allocates and initializes a ListRec structure in preparation for
subsequent List Manager calls.
rView is a Rect that specifies the size and location (in coordinates local to
theWindow ), of the interior of the list. The scroll bars (if any)
are drawn outside this rectangle, so if scrollHoriz and/or scrollVert
are TRUE, the window should be 15 pixels larger on the right and/or
bottom of rView.
rDataBnds is a Rect that identifies the bounds of the data as a 2-dimensional
array. topLeft identifies the top, leftmost cell and botRight is the
bottom, rightmost cell. For instance, (0,0)(1,x) is a one- column
list with x elements (as used by ResEdit). If rDataBnds =
(0,0)(10,15), the list will have 10 columns and 15 rows with cells
(0,0) through (9,14).
You can use (0,0)(0,0) if you don't know how many cells you'll
need. In that case, use LAddColumn and LAddRow to prepare some
empty cells.
cellSize is a Point, used to identify the size of each cell in pixels. Think of it
as the botRight of a rectangle whose topLeft is at (0,0). If either the
horizontal or vertical part of cellSize is 0, that part is set to a
default, as follows:
Height is the ascent+descent+leading of theWindow's current font.
Width is the width (in pixels) of rView divided by the number of
columns; i.e.,
Width=(rView.right-rView.left)/(rDataBnds.right-rDataBnds.left)
When each cell is drawn, its contents are clipped to a rectangle of
this size.
procID is a short integer; the resource ID of a custom list-handling
procedure (type 'LDEF'). Use 0 to specify the standard list definition
function. A custom handler could allow you to exceed the 32K
maximum data size or display different sizes of text or images in the
cells.
theWindow is a WindowPtr identifying the window in which the list should be
displayed. If scroll bars are used, its portRect should be larger than
rView. You may wish to prepare the window by pre-setting its font,
etc.
drawIt is a Boolean that specifies whether or not to draw the list. It is one
of:
FALSE Don't draw any part of it yet. Use LDoDraw later.
TRUE Draw the list immediately.
hasGrow is a Boolean that changes the way the scroll bars are drawn. If both
scrollHoriz and scrollVert are FALSE, this parameter is ignored.
Otherwise, it is one of:
FALSE Draw scroll bars all the way to the end of rView.
TRUE Leave room for a grow box below the bottom right corner of
rView. (You must draw it yourself via DrawGrowIcon)
scrollHoriz and . . .
scrollVert are Booleans that specify which scroll bars to draw to the right
and/or bottom of rView in theWindow. TRUE specifies to draw the
control.
Returns: a ListHandle; a handle leading to a variable-length ListRec
structure (i.e. theList ). The structure itself is a relocatable block
on the heap and occupies 87 bytes plus 2 bytes for each cell (an index
into the cell data). The cell data is stored in a separate area on the
heap and cannot exceed 32K.
Notes: Before calling LNew, you should have created a window via NewWindow
(or GetNewWindow) and the various Managers should have been
initialized previously via InitGraf, InitFonts, InitWindows,
InitMenus, and TEInit (in that order). When finished with the list, use
LDispose to free up all memory it used.
Note: The maximum amount of data that can be stored in a list is 32K.
However, the standard 'LDEF' becomes inefficient long before you reach
that limit.
You may want to delay displaying the list until you have initialized all the
cell data (see LSetCell). Just set drawIt to FALSE in the call to LNew,
then call LDoDraw, and LUpdate at an appropriate moment.
Several fields of the ListRec structure are important but can only be
accessed directly. For instance, to minimize white space, you may want to
set the indent field. Example:
TextFont( geneva );
TextSize( 10 );
SetPt( &cellSz, 60, 10 ); /* normally cuts off descenders */
theList = LNew( &rView, &rBounds, cellSz, 0, listWindow, 1,0,0,0 );
if ( theList == 0 ) { . . . handle the error . . . }
(* theList)->indent.v -= 2; /* less space above may solve problem */
The selFlags field is also important; it identifies how multiple selections
are made (i.e., via Shift-clicking, etc.). The default setting of 0 works best
for selecting rectangular groups of cells. To customize for other cases, set
selFlags directly:
(* theList)->selFlags= lOnlyOne; /* e.g., prohibit multiple selections */
(* theList)->selFlags=lNoRect | lUseSense; /*e.g., Shift toggles selection
*/
See ListRec for options with the selFlags field.
See LClick for information on using a list in a dialog box.
The following example shows a sequence for bringing up a 2-dimensional
list and letting the user select from it. The result might look like this:
Example
#include <Lists.h>
#include
ListHandle theList; ¯/* will lead to a ListRec */
Rect rView, rBounds;
Point pCellSz, theCell;
short h,v, len;
WindowPtr listWindow;
char s[MAX_CELL_TEXT+1]; /* temp string to hold cell contents */
listWindow = GetNewWindow( LWIN_ID, 0, -1); /* get from resource */
SetPort( listWindow );
TextFont( geneva ); TextSize( 10 ); /* set font for cells */
pCellSz.h=0; pCellSz.v=0; [TOKEN:12074] force auto calculate */
rView = listWindow->portRect; /* get size from resource */
rView.right -= 15;rView.bottom -= 15; /* leave room for scroll bars */
SetRect( &rBounds, 0,0, 3,20); /* list array is 3 wide x 20 high */
theList = LNew( &rView, [TOKEN:12074] viewing area */
&rBounds, [TOKEN:12074] cell array size */
pCellSz, [TOKEN:12074] cell size in pixels */
0, [TOKEN:12074] use standard 'LDEF' */
listWindow, [TOKEN:12074] put it in this window */
TRUE, [TOKEN:12074] DO display it now */
TRUE, [TOKEN:12074] grow icon WILL be used */
TRUE, FALSE ); [TOKEN:12074] both horiz and vert scrolling */
if (theList == 0) { printf("Error in LNew\n"); ExitToShell(); }
for ( h=0; h<3; h++ ) {
for ( v=0; v<20; v++ ) {
sprintf( s, "Cell %d,%d", h,v ); /* set up the text contents */
SetPt( &theCell, h,v );
LSetCell( s, strlen(s), theCell, theList ); /* store the data */
}
}
DrawGrowIcon( listWindow ); /* not done automatically */
(* theList)->selFlags = lNoRect; /* more intuitive selecting */
/*... in the event loop, a mouse-down occurs in content region of listWindow */
LClick( localPt, modifiers, theList ); /* handle the mouse data */
/* find which cell was selected */
theCell.h=theCell.v=0; [TOKEN:12074] to search entire array */
if ( LGetSelect( TRUE, &theCell, theList ) ) {
j=MAX_CELL_TEXT; [TOKEN:12074] length of buffer s[] */
LGetCell( s, &len, theCell, theList ); /* get contents */
s[len]=0; [TOKEN:12074] force ASCIIZ for printf() */
printf("Cell (%d,%d) contains text '%s'\n", theCell.h, theCell.v, s );
}
Referenced by (67):